home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / ftw.z / ftw
Encoding:
Text File  |  1998-10-20  |  11.8 KB  |  198 lines
  1.  
  2.  
  3.  
  4. ffffttttwwww((((3333CCCC))))                                                                ffffttttwwww((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _ffff_tttt_wwww, _ffff_tttt_wwww_6666_4444, _nnnn_ffff_tttt_wwww _nnnn_ffff_tttt_wwww_6666_4444 - walk a file tree
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ffff_tttt_wwww_...._hhhh_>>>>
  13.  
  14.      _iiii_nnnn_tttt _ffff_tttt_wwww _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_pppp_aaaa_tttt_hhhh_,,,, _iiii_nnnn_tttt _((((_****_ffff_nnnn_)))) _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_,,,, _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt
  15.          _ssss_tttt_aaaa_tttt _****_,,,, _iiii_nnnn_tttt_))))_,,,, _iiii_nnnn_tttt _dddd_eeee_pppp_tttt_hhhh_))))_;;;;
  16.  
  17.      _iiii_nnnn_tttt _ffff_tttt_wwww_6666_4444 _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_pppp_aaaa_tttt_hhhh_,,,, _iiii_nnnn_tttt _((((_****_ffff_nnnn_)))) _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_,,,, _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt
  18.          _ssss_tttt_aaaa_tttt_6666_4444 _****_,,,, _iiii_nnnn_tttt_))))_,,,, _iiii_nnnn_tttt _dddd_eeee_pppp_tttt_hhhh_))))_;;;;
  19.  
  20.      _iiii_nnnn_tttt _nnnn_ffff_tttt_wwww _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_pppp_aaaa_tttt_hhhh_,,,, _iiii_nnnn_tttt _((((_****_ffff_nnnn_)))) _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_,,,, _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt
  21.          _ssss_tttt_aaaa_tttt _****_,,,, _iiii_nnnn_tttt_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _FFFF_TTTT_WWWW_****_))))_,,,, _iiii_nnnn_tttt _dddd_eeee_pppp_tttt_hhhh_,,,, _iiii_nnnn_tttt _ffff_llll_aaaa_gggg_ssss_))))_;;;;
  22.  
  23.      _iiii_nnnn_tttt _nnnn_ffff_tttt_wwww_6666_4444 _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_pppp_aaaa_tttt_hhhh_,,,, _iiii_nnnn_tttt _((((_****_ffff_nnnn_)))) _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_,,,, _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt
  24.          _ssss_tttt_aaaa_tttt_6666_4444 _****_,,,, _iiii_nnnn_tttt_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _FFFF_TTTT_WWWW_****_))))_,,,, _iiii_nnnn_tttt _dddd_eeee_pppp_tttt_hhhh_,,,, _iiii_nnnn_tttt _ffff_llll_aaaa_gggg_ssss_))))_;;;;
  25.  
  26. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  27.      _ffff_tttt_wwww recursively descends the directory hierarchy rooted in _p_a_t_h.  For
  28.      each object in the hierarchy, _ffff_tttt_wwww calls the user-defined function _f_n,
  29.      passing it a pointer to a null-terminated character string containing the
  30.      name of the object, a pointer to a _ssss_tttt_aaaa_tttt structure (see _ssss_tttt_aaaa_tttt(2))
  31.      containing information about the object, and an integer.  Possible values
  32.      of the integer, defined in the _ffff_tttt_wwww_...._hhhh header file, are:
  33.  
  34.      _FFFF_TTTT_WWWW______FFFF       The object is a file.
  35.  
  36.      _FFFF_TTTT_WWWW______DDDD       The object is a directory.
  37.  
  38.      _FFFF_TTTT_WWWW______DDDD_NNNN_RRRR     The object is a directory that cannot be read.  Descendants
  39.                  of the directory will not be processed.
  40.  
  41.      _FFFF_TTTT_WWWW______NNNN_SSSS      _ssss_tttt_aaaa_tttt failed on the object because of lack of appropriate
  42.                  permission or the object is a symbolic link that points to a
  43.                  non-existent file. The stat buffer passed to _f_n is undefined.
  44.  
  45.      _ffff_tttt_wwww visits a directory before visiting any of its descendants.
  46.  
  47.      The tree traversal continues until the tree is exhausted, an invocation
  48.      of _f_n returns a nonzero value, or some error is detected within _ffff_tttt_wwww (such
  49.      as an I/O error).  If the tree is exhausted, _ffff_tttt_wwww returns zero.  If _f_n
  50.      returns a nonzero value, _ffff_tttt_wwww stops its tree traversal and returns
  51.      whatever value was returned by _f_n.  If _ffff_tttt_wwww detects an error other than
  52.      _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS, it returns -1, and sets the error type in _eeee_rrrr_rrrr_nnnn_oooo.
  53.  
  54.      The function _ffff_tttt_wwww_6666_4444 is identical to _ffff_tttt_wwww except that it passes a pointer to
  55.      a _ssss_tttt_aaaa_tttt_6666_4444 structure (see _ssss_tttt_aaaa_tttt_6666_4444(2)) to the user supplied function _f_n.
  56.  
  57.      The function _nnnn_ffff_tttt_wwww is similar to _ffff_tttt_wwww except that it takes an additional
  58.      argument, _f_l_a_g_s.  The _f_l_a_g_s field is used to specify:
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ffffttttwwww((((3333CCCC))))                                                                ffffttttwwww((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      _FFFF_TTTT_WWWW______PPPP_HHHH_YYYY_SSSS    Physical walk, does not follow symbolic links.  Otherwise,
  75.                  _nnnn_ffff_tttt_wwww will follow links but will not walk down any path that
  76.                  crosses itself.
  77.  
  78.      _FFFF_TTTT_WWWW______MMMM_OOOO_UUUU_NNNN_TTTT   The walk will not cross a mount point.
  79.  
  80.      _FFFF_TTTT_WWWW______DDDD_EEEE_PPPP_TTTT_HHHH   All subdirectories will be visited before the directory
  81.                  itself.
  82.  
  83.      _FFFF_TTTT_WWWW______CCCC_HHHH_DDDD_IIII_RRRR   The walk will change to each directory before reading it.
  84.  
  85.      The function _nnnn_ffff_tttt_wwww calls _f_n with four arguments at each file and
  86.      directory.  The first argument is the pathname of the object, the second
  87.      is a pointer to the _ssss_tttt_aaaa_tttt buffer, the third is an integer giving
  88.      additional information, and the fourth is a _ssss_tttt_rrrr_uuuu_cccc_tttt _FFFF_TTTT_WWWW that contains the
  89.      following members:
  90.           _iiii_nnnn_tttt _bbbb_aaaa_ssss_eeee_;;;;
  91.           _iiii_nnnn_tttt _llll_eeee_vvvv_eeee_llll_;;;;
  92.      _bbbb_aaaa_ssss_eeee is the offset into the pathname of the base name of the object.
  93.      _llll_eeee_vvvv_eeee_llll indicates the depth relative to the rest of the walk, where the
  94.      root level is zero.
  95.  
  96.      The values of the third argument are as follows:
  97.  
  98.      _FFFF_TTTT_WWWW______FFFF       The object is a file.
  99.  
  100.      _FFFF_TTTT_WWWW______DDDD       The object is a directory.
  101.  
  102.      _FFFF_TTTT_WWWW______DDDD_PPPP      The object is a directory and subdirectories have been
  103.                  visited.
  104.  
  105.      _FFFF_TTTT_WWWW______SSSS_LLLL_NNNN     The object is a symbolic link that points to a non-existent
  106.                  file.
  107.  
  108.      _FFFF_TTTT_WWWW______DDDD_NNNN_RRRR     The object is a directory that cannot be read.  _f_n will not
  109.                  be called for any of its descendants.
  110.  
  111.      _FFFF_TTTT_WWWW______NNNN_SSSS      _ssss_tttt_aaaa_tttt failed on the object because of lack of appropriate
  112.                  permission.  The stat buffer passed to _f_n is undefined.  _ssss_tttt_aaaa_tttt
  113.                  failure other than lack of appropriate permission (_EEEE_AAAA_CCCC_CCCC_EEEE_SSSS) is
  114.                  considered an error and _nnnn_ffff_tttt_wwww will return -1.
  115.  
  116.      The function _nnnn_ffff_tttt_wwww_6666_4444 is identical to _nnnn_ffff_tttt_wwww except that it passes a pointer
  117.      to a _ssss_tttt_aaaa_tttt_6666_4444 structure (see _ssss_tttt_aaaa_tttt_6666_4444(2)) to the user supplied function _f_n.
  118.  
  119.      Both _ffff_tttt_wwww and _nnnn_ffff_tttt_wwww use one file descriptor for each level in the tree.
  120.      The _d_e_p_t_h argument limits the number of file descriptors so used.  If
  121.      _d_e_p_t_h is zero or negative, the effect is the same as if it were 1.  _d_e_p_t_h
  122.      must not be greater than the number of file descriptors currently
  123.      available for use.  _ffff_tttt_wwww will run faster if _d_e_p_t_h is at least as large as
  124.      the number of levels in the tree.  When _ffff_tttt_wwww and _nnnn_ffff_tttt_wwww return, they close
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. ffffttttwwww((((3333CCCC))))                                                                ffffttttwwww((((3333CCCC))))
  136.  
  137.  
  138.  
  139.      any file descriptors they have opened; they do not close any file
  140.      descriptors that may have been opened by _f_n.
  141.  
  142. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  143.      _ssss_tttt_aaaa_tttt(2), _mmmm_aaaa_llll_llll_oooo_cccc(3C).
  144.  
  145. NNNNOOOOTTTTEEEESSSS
  146.      Because _ffff_tttt_wwww is recursive, it is possible for it to terminate with a
  147.      memory fault when applied to very deep file structures.
  148.  
  149.      _ffff_tttt_wwww uses _mmmm_aaaa_llll_llll_oooo_cccc(3C) to allocate dynamic storage during its operation.  If
  150.      _ffff_tttt_wwww is forcibly terminated, such as by _llll_oooo_nnnn_gggg_jjjj_mmmm_pppp being executed by _f_n or an
  151.      interrupt routine, _ffff_tttt_wwww will not have a chance to free that storage, so it
  152.      will remain permanently allocated.  A safe way to handle interrupts is to
  153.      store the fact that an interrupt has occurred, and arrange to have _f_n
  154.      return a nonzero value at its next invocation.
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.